Hermes Agent完全实战指南
前言
用过 Claude Code 或 Codex CLI 的人大概都有这个体验:Agent 本身挺强,但你得花大量时间给它"搭环境"——写 AGENTS.md、写验证脚本、设计 Skills、维护进度文件、配置 MCP、管理上下文。Agent 的大部分失败不是模型不会写代码,而是周围的工程基础设施没跟上。
这套基础设施,业界叫 Harness——给 Agent 准备的操作环境和约束系统。问题是,搭 Harness 本身就是一个工程量巨大的事,一个资深工程师可能需要几周才能把一个项目的 Harness 搭到位。
然后 Nous Research 做了一件事:把 Harness 产品化,做成了一个开箱即用的 Agent 框架。
这就是 Hermes Agent——MIT 协议开源,2026 年 2 月发布,两个月拿下 27K+ Stars。
一句话概括:Hermes Agent 不是又一个"更聪明的 AI 编码工具"。它是一个自带三层记忆、自动生成 Skills、支持 15+ 平台的 Agent 操作系统——别的工具让你自己搭 Harness,Hermes 出厂就带。
1. Hermes Agent 是什么
1.1 先说人话
Hermes Agent 是 Nous Research 做的开源 AI Agent 框架。它和 Claude Code、Codex CLI 最大的区别在于:它不只是一个编码助手,它是一个可以 24/7 自主运行的个人 AI Agent。
它能接入 200+ 个模型(不锁定厂商),通过 Telegram、Discord、Slack、微信、飞书等 15+ 个平台跟你对话,而且——它会记住你,会从经验中自动生成工作流,下次遇到类似问题直接调用,越用越顺手。
1.2 一张表看定位
| 维度 | Claude Code | Codex CLI | Hermes Agent |
|---|---|---|---|
| 定位 | 交互式编码 Agent | 后台编码 Agent | 全能个人 AI Agent |
| 模型绑定 | Claude only | OpenAI only | 200+ 模型(OpenRouter、Anthropic、OpenAI、Gemini、本地模型) |
| 运行模式 | 人在回路,实时交互 | 后台任务,异步执行 | 两者都支持 + 7x24 自主运行 |
| 记忆 | 手动维护 CLAUDE.md | 无持久记忆 | 三层自动记忆(Session + Persistent + Skill) |
| Skills | 手动编写 SKILL.md | 无 | 自动生成 + 自动修正 + 社区 Hub |
| 对话平台 | 终端 CLI | 终端 CLI | 15+ 平台(Telegram、Discord、微信、飞书等) |
| IDE 集成 | VS Code、JetBrains | VS Code | ACP 适配器(VS Code、Zed、JetBrains) |
| 代码智能 | LSP、AST 感知 | 终端 + 文件操作 | 终端 + 文件操作(无 LSP) |
| 开源 | 否 | 是(MIT) | 是(MIT) |
| 最适合 | 复杂编码和重构 | 批量编码任务 | 个人助理 + 跨平台自动化 + 持久任务 |
一个关键区分:Claude Code 是"白天的结对编程搭档",Hermes 是"全天候的个人 AI 助理"。 大多数重度用户会同时用两者——Claude Code 负责交互式编码,Hermes 负责持久任务、定时调度、跨平台消息处理。
2. 架构全景
2.1 五层架构
flowchart TB
subgraph L1["Layer 1: 对话入口"]
CLI["终端 CLI / TUI"]
TG["Telegram"]
DC["Discord"]
SL["Slack"]
WX["微信 / 飞书 / 钉钉"]
MORE["Signal / WhatsApp / Email / SMS / ..."]
end
subgraph L2["Layer 2: Gateway 统一网关"]
GW["GatewayRunner
会话管理 + 平台适配"]
end
subgraph L3["Layer 3: Agent 核心"]
LOOP["AIAgent 主循环
消息 → 工具调用 → 结果 → 循环"]
MEM["三层记忆
Session + Persistent + Skill"]
CTX["上下文压缩
保护头尾,压缩中间"]
end
subgraph L4["Layer 4: 工具层"]
TOOLS["60+ 内建工具"]
MCP["MCP Client
6000+ 外部应用"]
PLUGIN["插件系统
14 个生命周期 Hook"]
end
subgraph L5["Layer 5: 执行后端"]
LOCAL["本地终端"]
DOCKER["Docker"]
SSH["SSH"]
MODAL["Modal Serverless"]
DAYTONA["Daytona"]
end
L1 --> L2 --> L3 --> L4 --> L52.2 项目目录结构
hermes-agent/
├── run_agent.py # AIAgent 类,核心对话循环(~625KB)
├── model_tools.py # 工具编排层:发现、分发、Schema 提供
├── toolsets.py # Toolset 定义和解析
├── cli.py # HermesCLI 类,交互式终端
├── hermes_state.py # SessionDB,SQLite + FTS5 全文搜索
├── agent/ # Agent 内部组件
│ ├── anthropic_adapter.py # Anthropic 原生适配器
│ ├── gemini_native_adapter.py
│ ├── bedrock_adapter.py
│ ├── memory_manager.py # 可插拔记忆后端
│ ├── prompt_builder.py # Prompt 构建(Skills 注入)
│ ├── context_compressor.py # 上下文压缩
│ ├── skill_utils.py # Skill 加载和匹配
│ └── shell_hooks.py # Shell Hook 系统(兼容 Claude Code 协议)
├── tools/ # 60+ 工具实现
│ ├── registry.py # 自注册工具中心
│ ├── delegate_tool.py # Subagent 委派
│ ├── skill_manager_tool.py # Skill 管理
│ └── environments/ # 执行后端(Local、Docker、SSH、Modal...)
├── skills/ # 内建 Skills(按分类目录组织)
├── optional-skills/ # 可选 Skills(按需安装)
├── gateway/ # 消息网关
│ ├── run.py # GatewayRunner
│ └── platforms/ # 15+ 平台适配器
├── plugins/ # 插件系统
├── cron/ # 定时任务调度器
├── acp_adapter/ # IDE 集成(VS Code / Zed / JetBrains)
├── ui-tui/ # Ink (React/TypeScript) 终端 UI
├── AGENTS.md # AI 编码工具的开发指南(752 行)
└── config.yaml # 统一 YAML 配置
3. 工具系统:60+ 工具的自注册模式
3.1 先说人话
Hermes 的工具不需要手动注册。每个工具文件在被 import 时自动向中央注册表声明自己——名字、所属 Toolset、JSON Schema、处理函数。这意味着加一个新工具只需要写一个 Python 文件,不用改任何配置。
3.2 注册机制
# tools/my_tool.py
from tools.registry import registry
registry.register(
name="my_tool",
toolset="hermes-cli",
schema={
"type": "function",
"function": {
"name": "my_tool",
"description": "做某件事",
"parameters": {
"type": "object",
"properties": {
"input": {"type": "string", "description": "输入内容"}
},
"required": ["input"]
}
}
},
handler=my_handler_function
)
发现过程:model_tools.py 调用 discover_builtin_tools(),用 AST 解析每个 tools/*.py 文件,找到包含 registry.register() 调用的模块才 import——不会盲目导入所有文件,避免了循环依赖。
3.3 Toolset 分组
工具通过 Toolset 分组,不同场景加载不同工具集:
| Toolset | 用途 | 包含工具数 |
|---|---|---|
_HERMES_CORE_TOOLS | 所有平台共享的核心工具 | ~30 |
hermes-cli | 终端交互 | 核心 + CLI 专属 |
hermes-telegram | Telegram 对话 | 核心 + 消息专属 |
hermes-acp | IDE 集成 | 核心 - 音频 - 澄清 UI |
web / browser | 网页操作 | 浏览器自动化工具 |
safe | 安全模式 | 去掉终端执行等高风险工具 |
Toolset 支持递归包含(includes 字段),组合灵活。
3.4 工具调用流程
flowchart LR
A["AIAgent 主循环"] --> B["model_tools.handle_function_call()"]
B --> C["coerce_tool_args()
类型强转(防 LLM 字符串漂移)"]
C --> D["Plugin pre_tool_call Hook
可阻断"]
D --> E["registry.dispatch()
执行工具处理函数"]
E --> F["Plugin post_tool_call Hook"]
F --> G["Plugin transform_tool_result Hook"]
G --> H["返回结果给 Agent 循环"]有四个特殊工具(todo、memory、session_search、delegate_task)被 Agent 主循环直接拦截处理,不走通用分发流程——因为它们需要访问 Agent 的内部状态。
4. 三层记忆:Session / Persistent / Skill
4.1 先说人话
大多数 AI 工具的记忆是"一次性的"——关掉窗口就忘了。Claude Code 的 CLAUDE.md 好一些,但需要你手动维护。
Hermes 的记忆是自动的、三层的、跨会话持久的。它不是把所有历史塞进 context——而是按需检索,只拿相关的部分。
4.2 三层结构
| 层 | 存储位置 | 内容 | 生命周期 |
|---|---|---|---|
| Session(会话) | SQLite + FTS5 | 完整对话记录,全文索引 | 永久存储,按需检索 |
| Persistent(持久) | ~/.hermes/memories/MEMORY.md + USER.md | Agent 笔记 + 用户画像 | 跨会话持久,每次加载 |
| Skill(技能) | ~/.hermes/skills/*.md | 结构化工作流 | 跨会话持久,自动匹配加载 |
4.3 关键工程细节
持久记忆有硬上限。 MEMORY.md 限制在 2,200 字符(~800 tokens),USER.md 限制在 1,375 字符(~500 tokens)。这不是偷懒——每个记忆 token 都是不可缓存的 system prompt token,上限太高会直接拉高 API 成本。
冻结快照模式。 记忆在会话开始时一次性快照,中途的写入只存到磁盘、不影响当前会话。这是一个精心设计:保护 Anthropic 的 prefix cache,避免每次记忆变更都让缓存失效。大部分团队在自建 Agent 时会忽略这个优化,导致 API 成本翻倍。
文件锁。 用 fcntl(Unix)/ msvcrt(Windows)防止多个 Agent 进程同时写入记忆文件导致数据损坏。
注入扫描。 每次写入记忆前都会扫描内容,检测 prompt injection 模式、凭证外泄指令(curl/wget 带 token)、SSH 后门签名等。
4.4 按需检索 vs 全量加载
传统做法是把所有历史塞进 context window。Hermes 的做法是 FTS5 全文搜索——只检索当前任务相关的历史片段。
这意味着你可以积累几个月的对话历史,而不会降低 Agent 的响应质量或拖慢速度。
5. 自进化 Skills:从经验中自动生成工作流
5.1 先说人话
Claude Code 的 Skills 需要你手动写 SKILL.md。Hermes 的 Skills 是Agent 自己写的——做完一个复杂任务后,它会自动把步骤提炼成一个 Skill 文件,下次遇到类似问题直接调用。
用户纠正了 Agent 的做法?它会自动更新对应的 Skill。这就是"自进化"的含义——不是 Agent 改自己的代码,而是 Agent 改自己的行为指令。
5.2 Skill 文件结构
---
name: k8s-pod-debug
description: 排查 K8s Pod 启动失败
version: 1.0.0
platforms: [linux, macos]
metadata:
hermes:
tags: [Kubernetes, 排障]
category: devops
prerequisites:
commands: [kubectl]
---
# K8s Pod 启动失败排查
## 步骤
1. `kubectl get pods -n <namespace>` 确认 Pod 状态
2. 如果 ImagePullBackOff → `kubectl describe pod` 看 Events
3. 如果 CrashLoopBackOff → `kubectl logs` 看应用日志
4. 定位根因后,最小化修改 YAML
5. `kubectl apply` 后验证 Pod 恢复 Running
Skills 是 Markdown——是数据,不是代码。它塑造 prompt,但不修改 Agent 源码。用户可以随时审查、编辑或删除任何 Skill。
5.3 Skill 来源
| 来源 | 说明 |
|---|---|
| 内建 | skills/ 目录,40+ 个预置 Skill(Apple、GitHub、MLOps、创意写作等) |
| 可选 | optional-skills/,较重的 Skill,按需安装:hermes skills install official/<category>/<skill> |
| Agent 自动生成 | 从复杂任务中提炼,存入 ~/.hermes/skills/ |
| 社区 Hub | 兼容 agentskills.io 标准,一键安装社区 Skill |
| 用户自建 | 手动放入 ~/.hermes/skills/ |
5.4 自进化循环
flowchart TB
A["完成一个复杂任务"] --> B{"自动回顾"}
B -->|"有什么要记住的?"| C["写入 MEMORY.md"]
B -->|"这是个重复模式?"| D["自动创建 Skill"]
B -->|"用户纠正了?"| E["更新现有 Skill"]
D --> F["下次遇到类似问题
自动匹配并调用 Skill"]
E --> F
C --> F5.5 需要清醒认识的地方
"自进化"听起来很科幻,但实际机制很朴素。 源码级审计(Saulius.io 的分析)表明,Hermes 的"自进化"分解为四个正交机制:
- Skill 自动生成:从任务轨迹中提炼 Markdown 文件
- 持久记忆:自动整理用户偏好和习惯
- 离线 RL 微调:收集轨迹数据供人工监督的微调(用户必须手动触发
rl_start_training,Agent 不会自行启动) - Pull 更新:
hermes update拉取上游代码
没有任何一个机制涉及 Agent 自主修改源码、自动重写 prompt、或自主评分改进。 真正的递归自我改进仍然是学术前沿。
但这不影响它的实用性。一个会自动写笔记、自动总结 SOP、自动记住你偏好的 Agent,已经比 90% 的"每次从零开始"的工具好用太多了。
6. 多平台 Gateway
6.1 先说人话
Claude Code 和 Codex CLI 只能在终端里用。Hermes 可以同时连接 15+ 个消息平台——你在 Telegram 上问的问题、在终端里的后续操作、在 Discord 里的追问,共享同一个记忆和上下文。
6.2 支持平台
| 平台 | 特殊能力 |
|---|---|
| Telegram | 语音转文字、菜单自动生成 |
| Discord | 服务器 + 私信 |
| Slack | 频道 + 私信 |
| 通过 API | |
| Signal | 端到端加密 |
| 微信 / 企业微信 | 媒体上传 |
| 飞书 / Lark | 机器人接口 |
| 钉钉 | 机器人接口 |
| Matrix | 去中心化协议 |
| Mattermost | 自托管 |
| 收发邮件 | |
| SMS | 通过 Twilio |
| Home Assistant | 智能家居控制 |
| Open WebUI | Web 界面 |
| API Server | 自定义集成 |
6.3 架构要点
Gateway 是一个统一进程,同时管理所有平台的连接。核心设计:
- 每个会话有独立的 AIAgent 实例(最多 128 个,1 小时空闲后释放)
- 对话是平台无关的——Telegram 上开始的对话可以在终端里继续
- 每条消息保留发送者信息,群聊中能区分不同用户
- 语音消息自动转文字
这是 Hermes 最独特的组件,也是它与纯编码工具拉开定位差距的地方。
7. 安全五道防线
7.1 先说人话
一个能读写文件、执行命令、访问 API 的 Agent,安全问题不是可选项。Hermes 内建了五道防线,不需要额外配置。
7.2 五道防线详解
| 防线 | 机制 | 防什么 |
|---|---|---|
| 记忆注入扫描 | 正则检测 prompt injection、凭证外泄指令、角色劫持 | 防止恶意内容通过记忆系统注入 |
| 上下文文件注入扫描 | 检测 AGENTS.md 等文件中的隐形 Unicode、隐藏 HTML div、注入模式 | 防止项目文件被植入攻击指令 |
| MCP 包 OSV 检查 | 启动 MCP Server 前验证 npm/pypi 包是否有已知漏洞 | 防止恶意依赖 |
| 凭证脱敏 | 从所有终端输出和聊天记录中剥离 API Key、Token、Secret | 防止密钥泄露 |
| 结构化上下文压缩 | 压缩中间对话时用 Resolved/Pending 追踪 + "不同助手"移交帧 | 防止被压缩的旧指令被重新执行 |
独立评估的结论:这五道防线"对任何 Agent 都有独立价值",即使你不用 Hermes 也值得参考。
但也要注意边界:Hermes 明确声明安全模型是"保护运营者免受 LLM 行为影响,不防御恶意共租户"。个人使用足够,多租户场景需要额外加固。
8. 实战:从安装到体验学习循环
8.1 安装
三种部署方式,推荐从本地安装开始:
# 方式一:本地安装(macOS / Linux / WSL2)
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
# 方式二:Docker(适合 7x24 运行)
docker pull nousresearch/hermes-agent
docker run -v ~/.hermes:/root/.hermes nousresearch/hermes-agent
# 方式三:$5 VPS(推荐的长期运行方案,内存占用 < 500MB)
# 在任意 VPS 上执行方式一的安装脚本即可
8.2 首次配置
安装后运行 hermes,首次会启动配置向导。核心配置在 ~/.hermes/config.yaml:
# ~/.hermes/config.yaml(关键配置项)
# 模型选择——不绑定厂商
model:
provider: openrouter # 或 anthropic / openai / ollama
model: anthropic/claude-sonnet-4-20250514
# 也可以用便宜模型做日常对话
cheap_model: deepseek/deepseek-chat
# 工具集
toolsets:
- hermes-cli
- web
- browser
# Skills 配置
skills:
auto_improve: true # 允许 Agent 自动创建和修改 Skills
external_dirs: # 额外 Skill 目录
- ~/my-skills/
# 消息网关(按需启用)
gateway:
telegram:
enabled: true
token: "YOUR_BOT_TOKEN"
discord:
enabled: false
API Key 放在 ~/.hermes/.env,不放 config.yaml:
# ~/.hermes/.env
OPENROUTER_API_KEY=sk-or-...
ANTHROPIC_API_KEY=sk-ant-...
8.3 体验自进化循环
启动 Hermes 后,做一个稍微复杂的任务:
> 帮我查一下 production 命名空间里所有 Pod 的资源使用情况,
找出 CPU request 超过 500m 但实际用量不到 100m 的 Pod,
生成一个优化建议
Agent 会:
- 执行
kubectl top pods和kubectl get pods -o json - 交叉比对 request 和实际用量
- 输出优化建议
任务完成后,自动回顾触发:
[Hermes] 检测到这是一个可复用的工作流。
已创建 Skill: k8s-resource-audit
位置: ~/.hermes/skills/k8s-resource-audit/SKILL.md
下次你说"帮我查一下资源浪费的 Pod",Agent 会直接调用这个 Skill,不再从零推理步骤。
如果你纠正了它——"下次先检查是否有 VPA 在管理这些 Pod"——它会更新 Skill 文件,加上 VPA 检查步骤。
8.4 跨平台对话
在终端里启动 Gateway:
hermes gateway start
然后在 Telegram 上给你的 Hermes Bot 发消息:
刚才那个 K8s 资源审计的结果,帮我发到 #ops-alerts Slack 频道
Hermes 记得你刚才的分析结果(跨平台共享记忆),直接执行。
9. 插件系统与 Hook
9.1 14 个生命周期 Hook
插件可以在 Agent 生命周期的 14 个节点注入逻辑:
| Hook | 触发时机 | 典型用途 |
|---|---|---|
pre_tool_call | 工具执行前 | 权限控制、参数校验 |
post_tool_call | 工具执行后 | 日志记录、结果缓存 |
transform_tool_result | 工具结果返回前 | 脱敏、格式化 |
pre_llm_call | LLM 调用前 | 注入额外上下文 |
post_llm_call | LLM 调用后 | Token 统计、成本追踪 |
on_session_start | 会话开始 | 加载项目上下文 |
on_session_end | 会话结束 | 生成摘要 |
9.2 Shell Hook 兼容 Claude Code
Hermes 的 Shell Hook 系统(agent/shell_hooks.py)刻意兼容 Claude Code 的 Hook 协议。它同时接受两种格式:
// Claude Code 格式
{"decision": "block", "reason": "不允许删除生产数据库"}
// Hermes 原生格式
{"action": "block", "message": "不允许删除生产数据库"}
这意味着你已有的 Claude Code Hook 脚本可以直接复用。
10. Subagent 委派
10.1 机制
Hermes 通过 delegate_tool.py 实现子 Agent 委派。主 Agent 可以生成隔离的子 Agent 来处理并行任务。
关键限制:
- 最大深度 2 层(子 Agent 不能再生子 Agent)
- 最多 3 个并发子 Agent
- 子 Agent 有受限的工具集:不能递归委派、不能访问记忆、不能发消息、不能执行代码
这些限制是刻意的——防止失控的递归调用和权限扩散。
10.2 与 Claude Code 对比
| 维度 | Claude Code | Hermes Agent |
|---|---|---|
| 子 Agent 机制 | Agent tool + Task tool,原生 Teams 支持 | delegate_tool,线程隔离 |
| 最大深度 | 无硬性限制 | 2 层 |
| 并发数 | 无硬性限制 | 3 个 |
| 子 Agent 权限 | 继承父 Agent | 受限(无记忆、无消息、无代码执行) |
11. 优势与局限
11.1 优势
多平台 Gateway 是独一份。 15+ 消息平台的统一接入,对话跨平台共享记忆——这是 Claude Code 和 Codex CLI 完全没有的能力。
模型自由。 200+ 模型随意切换,支持 OpenRouter 路由、本地 Ollama 模型、甚至中途换模型。不被任何厂商锁定。
自进化 Skills 降低维护成本。 不需要手动写 SKILL.md,Agent 从经验中自动生成和修正。对个人用户来说,这比手动维护 Harness 高效得多。
安全五道防线开箱即用。 不需要额外配置就有记忆注入扫描、凭证脱敏、MCP 漏洞检查。
部署成本极低。 一台 $5/月的 VPS,内存占用 < 500MB,就能 7x24 运行。
11.2 局限
编码能力不如 Claude Code。 没有 LSP、没有 AST 感知、没有原生 IDE 深度集成。做复杂的多文件重构,Claude Code 明显更强。
单体架构的维护风险。 CLI、Gateway、60+ 工具、RL 训练、15 个平台适配器全在一个仓库里。独立评估指出有 ~1,800 个 open issue,只有 30 个贡献者——"功能速度优先于稳定性"的信号。
自进化的审计缺口。 Skills 会自动修改,虽然改动是可 diff 的 Markdown,但现实是大多数用户不会去审查。"你能审计"和"你会审计"之间有很大的差距。在模糊领域,Agent 可能"越来越快、越来越自信地做错事"。
数据飞轮动机。 轨迹保存和 RL 组件的存在是为了给 Nous Research 的未来模型生成训练数据。这是透明的(MIT 协议、有文档说明),但值得了解。
测试套件有问题。 项目自己的文档警告不要直接运行 pytest,需要用 wrapper 脚本统一环境——说明测试和本地环境有耦合问题。
12. 决策指南
你需要一个 7x24 自主运行的 AI 助理吗?
→ 是:Hermes Agent(这是它的主场)
→ 否 ↓
你的核心需求是高质量代码编写和重构?
→ 是:Claude Code(LSP + AST 感知,编码质量最强)
→ 否 ↓
你需要跨 Telegram / Discord / 微信等平台的 AI 对话?
→ 是:Hermes Agent(唯一选择)
→ 否 ↓
你想避免厂商锁定,需要接入多种模型?
→ 是:Hermes Agent(200+ 模型)
→ 否 ↓
你需要后台批量处理编码任务?
→ 是:Codex CLI
→ 否:Claude Code(最成熟、最稳定的默认选择)
最务实的组合:Claude Code 当白班(交互式编码),Hermes 当夜班(持久任务、定时调度、跨平台消息)。
13. 核心参考资料
| 资料 | 来源 |
|---|---|
| Hermes Agent 官方仓库 | github.com/NousResearch/hermes-agent |
| Hermes Agent 官方文档 | hermes-agent.nousresearch.com/docs |
| 源码级架构审计:"自进化"到底意味着什么 | saulius.io |
| 独立技术评估(架构、优势、红旗) | michaeloboyle/gist |
| 2026 CLI Agent 横评(含 Hermes) | colombani.ai |
| Hermes Agent 30 天使用报告 | heyuan110.com |
| Hermes 自进化 AI 深度剖析 | dev.to/marwane |
| Hermes vs Claude Code vs OpenClaw 三方对比 | utilo.io |
| Agent 自进化战争 | towardsai.net |
| Hermes 记忆系统五层拆解 | dev.to/openwalrus |